'\" te
.\"  Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH BUFMOD 4M "Nov 11, 1997"
.SH NAME
bufmod \- STREAMS Buffer Module
.SH SYNOPSIS
.LP
.nf
\fB#include <sys/bufmod.h>\fR
.fi

.LP
.nf
\fBioctl(fd, I_PUSH, "bufmod");\fR
.fi

.SH DESCRIPTION
.sp
.LP
\fBbufmod\fR is a \fBSTREAMS\fR module that buffers incoming messages, reducing
the number of system calls and the associated overhead required to read and
process them. Although \fBbufmod\fR was originally designed to be used in
conjunction with \fBSTREAMS-based\fR networking device drivers, the version
described here is general purpose so that it can be used anywhere \fBSTREAMS\fR
input buffering is required.
.SS "Read-side Behavior"
.sp
.LP
The behavior of \fBbufmod\fR depends on various parameters and flags that can
be set and queried as described below under \fBIOCTLS\fR. \fBbufmod\fR collects
incoming \fBM_DATA\fR messages into chunks, passing each chunk upstream when
the chunk becomes full or the current read timeout expires. It optionally
converts \fBM_PROTO\fR messages to \fBM_DATA\fR and adds them to chunks as
well. It also optionally adds to each message a header containing a timestamp,
and a cumulative count of  messages dropped on the stream read side due to
resource exhaustion or flow control. Thedefault settings of \fBbufmod\fR allow
it to drop messages when flow control sets in or resources are exhausted;
disabling headers and explicitly requesting no drops makes \fBbufmod\fR pass
all messages through. Finally, \fBbufmod\fR is capable of truncating upstream
messages to a fixed, programmable length.
.sp
.LP
When a message arrives, \fBbufmod\fR processes it in several steps. The
following paragraphs discuss each step in turn.
.sp
.LP
Upon receiving a message from below, if the \fBSB_NO_HEADER\fR flag is not set,
\fBbufmod\fR immediately timestamps it and saves the current time value for
later insertion in the header described below.
.sp
.LP
Next, if \fBSB_NO_PROTO_CVT\fR is not set, \fBbufmod\fR converts all leading
\fBM_PROTO\fR blocks in the message to \fBM_DATA\fR blocks, altering only the
message type field and leaving the contents alone.
.sp
.LP
It then truncates the message to the current \fIsnapshot length\fR, which is
set with the \fBSBIOCSSNAP\fR \fBioctl\fR described below.
.sp
.LP
Afterwards, if \fBSB_NO_HEADER\fR is not set, \fBbufmod\fR prepends a header to
the converted message. This header is defined as follows.
.sp
.in +2
.nf
struct sb_hdr {
        uint_t   sbh_origlen;
        uint_t   sbh_msglen;
        uint_t   sbh_totlen;
        uint_t   sbh_drops;
#if defined(_LP64) || defined(_I32LPx)
        struct  timeval32 sbh_timestamp;
#else
        struct  timeval sbh_timestamp;
#endif /* !_LP64 */
};
.fi
.in -2

.sp
.LP
The \fBsbh_origlen\fR field gives the message's original length before
truncation in bytes. The \fBsbh_msglen\fR field gives the length in bytes of
the message after the truncation has been done. \fBsbh_totlen\fR gives the
distance in bytes from the start of the truncated message in the current chunk
(described below) to the start of the next message in the chunk; the value
reflects any padding necessary to insure correct data alignment for the host
machine and includes the length of the header itself. \fBsbh_drops\fR reports
the cumulative number of input messages that this instance of \fBbufmod\fR has
dropped due to flow control or resource exhaustion. In the current
implementation message dropping due to flow control can occur only if the
\fBSB_NO_DROPS\fR flag is not set. (Note: this accounts only for events
occurring within \fBbufmod\fR, and does not count messages dropped by
downstream or by upstream modules.) The \fBsbh_timestamp\fR field contains the
message arrival time expressed as a \fBstruct timeval\fR.
.sp
.LP
After preparing a message, \fBbufmod\fR attempts to add it to the end of the
current chunk, using the chunk size and timeout values to govern the addition.
The chunk size and timeout values are set and inspected using the \fBioctl()\fR
calls described below. If adding the new message would make the current chunk
grow larger than the chunk size, \fBbufmod\fR closes off the current chunk,
passing it up to the next module in line, and starts a new chunk. If adding the
message would still make the new chunk overflow, the module passes it upward in
an over-size chunk of its own. Otherwise, the module concatenates the message
to the end of the current chunk.
.sp
.LP
To ensure that messages do not languish forever in an accumulating chunk,
\fBbufmod\fR maintains a read timeout. Whenever this timeout expires, the
module closes off the current chunk and passes it upward. The module restarts
the timeout period when it receives a read side data message and a timeout is
not currently active. These two rules insure that \fBbufmod\fR minimizes the
number of chunks it produces during periods of intense message activity and
that it periodically disposes of all messages during slack intervals, but
avoids any timeout overhead when there is no activity.
.sp
.LP
\fBbufmod\fR handles other message types as follows. Upon receiving an
\fBM_FLUSH\fR message specifying that the read queue be flushed, the module
clears the currently accumulating chunk and passes the message on to the module
or driver above. (Note: \fBbufmod\fR uses zero length \fBM_CTL\fR messages for
internal synchronization and does not pass them through.) \fBbufmod\fR passes
all other messages through unaltered to its upper neighbor, maintaining message
order for non high priority messages by passing up any accumulated chunk first.
.sp
.LP
If the \fBSB_DEFER_CHUNK\fR flag is set, buffering does not begin until the
second message is received within the timeout window.
.sp
.LP
If the \fBSB_SEND_ON_WRITE\fR flag is set, \fBbufmod\fR passes up the read side
any buffered data when a message is received on the write side.
\fBSB_SEND_ON_WRITE\fR and \fBSB_DEFER_CHUNK\fR are often used together.
.SS "Write-side Behavior"
.sp
.LP
\fBbufmod\fR intercepts \fBM_IOCTL\fR messages for the \fBioctl\fRs described
below. The module passes all other messages through unaltered to its lower
neighbor. If \fBSB_SEND_ON_WRITE\fR is set, message arrival on the writer side
suffices to close and transmit the current read side chunk.
.SH IOCTLS
.sp
.LP
\fBbufmod\fR responds to the following \fBioctl\fRs.
.sp
.ne 2
.na
\fB\fBSBIOCSTIME\fR \fR
.ad
.RS 16n
Set the read timeout value to the value referred to by the \fBstruct timeval\fR
pointer given as argument. Setting the timeout value to zero has the
side-effect of forcing the chunk size to zero as well, so that the module will
pass all incoming messages upward immediately upon arrival. Negative values are
rejected with an \fBEINVAL\fR error.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCGTIME\fR \fR
.ad
.RS 16n
Return the read timeout in the \fBstruct timeval\fR pointed to by the argument.
If the timeout has been cleared with the \fBSBIOCCTIME\fR \fBioctl\fR, return
with an \fBERANGE\fR error.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCCTIME\fR \fR
.ad
.RS 16n
Clear the read timeout, effectively setting its value to infinity. This results
in no timeouts being active and the chunk being delivered when it is full.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCSCHUNK\fR \fR
.ad
.RS 16n
Set the chunk size to the value referred to by the \fIuint_t\fR pointer given
as argument. See Notes for a description of effect on stream head high water
mark.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCGCHUNK\fR \fR
.ad
.RS 16n
Return the chunk size in the \fIuint_t\fR pointed to by the argument.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCSSNAP\fR \fR
.ad
.RS 16n
Set the current snapshot length to the value given in the \fBuint_t\fR pointed
to by the \fBioctl\fR's final argument. \fBbufmod\fR interprets a snapshot
length value of zero as meaning infinity, so it will not alter the message. See
Notes for a description of effect on stream head high water mark.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCGSNAP\fR \fR
.ad
.RS 16n
Returns the current snapshot length in the \fBuint_t\fR pointed to by the
\fBioctl\fR's final argument.
.RE

.sp
.ne 2
.na
\fB\fBSBIOCSFLAGS\fR \fR
.ad
.RS 16n
Set the current flags to the value given in the \fBuint_t\fR pointed to by the
\fBioctl\fR's final argument. Possible values are a combination of the
following.
.sp
.ne 2
.na
\fB\fBSB_SEND_ON_WRITE\fR \fR
.ad
.RS 21n
Transmit the read side chunk on arrival of a message on the write side.
.RE

.sp
.ne 2
.na
\fB\fBSB_NO_HEADER\fR \fR
.ad
.RS 21n
Do not add headers to read side messages.
.RE

.sp
.ne 2
.na
\fB\fBSB_NO_DROPS\fR \fR
.ad
.RS 21n
Do not drop messages due to flow control upstream.
.RE

.sp
.ne 2
.na
\fB\fBSB_NO_PROTO_CVT\fR \fR
.ad
.RS 21n
Do not convert \fBM_PROTO\fR messages into \fBM_DATA\fR.
.RE

.sp
.ne 2
.na
\fB\fBSB_DEFER_CHUNK\fR \fR
.ad
.RS 21n
Begin buffering on arrival of the second read side message in a timeout
interval.
.RE

.RE

.sp
.ne 2
.na
\fB\fBSBIOCGFLAGS\fR \fR
.ad
.RS 16n
Returns the current flags in the \fBuint_t\fR pointed to by the \fBioctl\fR's
final argument.
.RE

.SH SEE ALSO
.sp
.LP
.BR pfmod (4M),
.BR dlpi (4P)
.SH NOTES
.sp
.LP
Older versions of \fBbufmod\fR did not support the behavioral flexibility
controlled by the \fBSBIOCSFLAGS\fR \fBioctl\fR. Applications that wish to take
advantage of this flexibility can guard themselves against old versions of the
module by invoking the \fBSBIOCGFLAGS\fR ioctl and checking for an \fBEINVAL\fR
error return.
.sp
.LP
When buffering is enabled by issuing an \fBSBIOCSCHUNK\fR ioctl to set the
chunk size to a non zero value,  \fBbufmod\fR sends a \fBSETOPTS\fR message to
adjust the stream head high and low water marks to accommodate the chunked
messages.
.sp
.LP
When buffering is disabled by setting the chunk size to zero, message
truncation can have a significant  influence on data traffic at the stream head
and therefore the stream head high and low water marks are adjusted to new
values appropriate for the smaller truncated message sizes.
.SH BUGS
.sp
.LP
\fBbufmod\fR does not defend itself against allocation failures, so that it is
possible, although very unlikely, for the stream head to use inappropriate high
and low water marks after the chunk size or  snapshot length have changed.
